feat: Add generated Open Graph images for docs pages - #769

Every docs page gets a social card matching the serverpod.dev feature-page design when its link is shared. Pages with an explicit image in frontmatter keep it; pages with an empty title (the CLI command wrappers) get no card rather than a blank one.

Screenshots

Creating endpoint methods

Database backups (Cloud)

Design

The layout reproduces the feature cards from pixel measurements of the real og:images at serverpod.dev: Inter Black 64px titles and Inter Regular 38.5px descriptions at the measured baselines, the sampled background gradient and glow, and the same icon footprint and 80px icon-to-text gap. Text is shaped with fontkit so Inter's GPOS kerning applies, which a stripe-composite comparison against the reference card confirms at antialiasing precision. The fonts are vendored from the pinned Inter 4.1 release with their OFL license.

Two decisions from design review are intentional:

• All cards use one generic 3D documentation icon, selected and supplied by the design team, replacing the earlier per-section Lucide icons. It sits on the logo column at 80% of the reference footprint and centers vertically on each card's text block.
• Descriptions cap at exactly two lines with word-boundary truncation, matching all nine feature cards. Pages can curate their card text with a concise frontmatter description.

How it works

• A local plugin (plugins/open-graph-images) renders one 1200x630 JPEG per unique card at build time. Card identity is a content hash of title, description, and a render fingerprint covering the renderer source, logo, icon, fonts, and library versions. The swizzled DocItem/Metadata computes the same ID client-side, so no manifest is needed and identical cards dedupe across all doc versions: 350 cards cover 1,599 pages (about 30 MB).
• Cards cache in .docusaurus with atomic writes and orphan cleanup, and the webpack DefinePlugin value is version-keyed so persistent caches can never serve stale IDs.
• A title or description character the pinned fonts cannot render fails the build with an error naming the page and source file.

Verification

• 32 unit tests cover ID parity between generator and theme, kerning, title size tiers, icon centering, truncation, fingerprint invalidation for every asset, empty-title suppression, multi-instance sites, and failure recovery.
• util/verify_open_graph_images.js gates both CI and deploy after each build: it parses every page's head with cheerio and checks that every og:image is a valid URL, every card reference resolves to an emitted, fully decodable 1200x630 JPEG, every eligible docs page carries an og:image, and no card is orphaned. The deploy workflow also runs the unit tests before building.

Prior art

The closest existing solution, @acid-info/docusaurus-og (Satori-based, alpha, pinned to Docusaurus 3.8.1), cannot reproduce the pixel-matched design, GPOS kerning, or the manifest-free architecture, so a small local plugin was built instead.

The second commit separately removes leftover Docusaurus template comments from docusaurus.config.js.